home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / lockf.z / lockf
Encoding:
Text File  |  2002-10-03  |  7.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))                                                            LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      lockf - record locking on files
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<uuuunnnniiiissssttttdddd....hhhh>>>>
  13.  
  14.      iiiinnnntttt lllloooocccckkkkffff ((((iiiinnnntttt ffffiiiillllddddeeeessss,,,, iiiinnnntttt ffffuuuunnnnccccttttiiiioooonnnn,,,, ooooffffffff____tttt ssssiiiizzzzeeee))));;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      The _l_o_c_k_f command will allow sections of a file to be locked; advisory or
  18.      mandatory write locks depending on the mode bits of the file [see
  19.      _c_h_m_o_d(2)].  Locking calls from other processes which attempt to lock the
  20.      locked file section will either return an error value or be put to sleep
  21.      until the resource becomes unlocked.  All the locks for a process are
  22.      removed when the process terminates.  [See _f_c_n_t_l(2) for more information
  23.      about record locking.]
  24.  
  25.      _F_i_l_d_e_s is an open file descriptor.  The file descriptor must have
  26.      O_WRONLY or O_RDWR permission in order to establish lock with this
  27.      function call.
  28.  
  29.      _F_u_n_c_t_i_o_n is a control value which specifies the action to be taken.  The
  30.      permissible values for _f_u_n_c_t_i_o_n are defined in <<<<uuuunnnniiiissssttttdddd....hhhh>>>> as follows:
  31.  
  32.      #define   F_ULOCK   0   /* Unlock a previously locked section */
  33.      #define   F_LOCK    1   /* Lock a section for exclusive use */
  34.      #define   F_TLOCK   2   /* Test and lock a section for exclusive use */
  35.      #define   F_TEST    3   /* Test section for other processes locks */
  36.  
  37.  
  38.      All other values of _f_u_n_c_t_i_o_n are reserved for future extensions and will
  39.      result in an error return if not implemented.
  40.  
  41.      F_TEST is used to detect if a lock by another process is present on the
  42.      specified section.  F_LOCK and F_TLOCK both lock a section of a file if
  43.      the section is available.  F_ULOCK removes locks from a section of the
  44.      file.
  45.  
  46.      _S_i_z_e is the number of contiguous bytes to be locked or unlocked.  The
  47.      resource to be locked starts at the current offset in the file and
  48.      extends forward for a positive size and backward for a negative size (the
  49.      preceding bytes up to but not including the current offset).  If _s_i_z_e is
  50.      zero, the section from the current offset through the largest file offset
  51.      is locked (i.e., from the current offset through the present or any
  52.      future end-of-file).  An area need not be allocated to the file in order
  53.      to be locked as such locks may exist past the end-of-file.
  54.  
  55.      The sections locked with F_LOCK or F_TLOCK may, in whole or in part,
  56.      contain or be contained by a previously locked section for the same
  57.      process.  When this occurs, or if adjacent sections occur, the sections
  58.      are combined into a single section.  If the request requires that a new
  59.      element be added to the table of active locks and this table is already
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))                                                            LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      full, an error is returned, and the new section is not locked.
  75.  
  76.      F_LOCK and F_TLOCK requests differ only by the action taken if the
  77.      resource is not available.  F_LOCK will cause the calling process to
  78.      sleep until the resource is available.  F_TLOCK will cause the function
  79.      to return a -1 and set _e_r_r_n_o to [EACCES] error if the section is already
  80.      locked by another process.
  81.  
  82.      F_ULOCK requests may, in whole or in part, release one or more locked
  83.      sections controlled by the process.  When sections are not fully
  84.      released, the remaining sections are still locked by the process.
  85.      Releasing the center section of a locked section requires an additional
  86.      element in the table of active locks.  If this table is full, an
  87.      [EDEADLK] error is returned and the requested section is not released.
  88.  
  89.      A potential for deadlock occurs if a process controlling a locked
  90.      resource is put to sleep by accessing another process's locked resource.
  91.      Thus calls to _l_o_c_k_f or _f_c_n_t_l scan for a deadlock prior to sleeping on a
  92.      locked resource.  An error return is made if sleeping on the locked
  93.      resource would cause a deadlock.
  94.  
  95.      Sleeping on a resource is interrupted with any signal.  The _a_l_a_r_m(2)
  96.      command may be used to provide a timeout facility in applications which
  97.      require this facility.
  98.  
  99.      The _l_o_c_k_f utility will fail if one or more of the following are true:
  100.  
  101.  
  102.      [EBADF]
  103.           _F_i_l_d_e_s is not a valid open file.
  104.  
  105.      [EACCES]
  106.           _C_m_d is F_TLOCK or F_TEST and the section is already locked by
  107.           another process.
  108.  
  109.      [EDEADLK]
  110.           _C_m_d is F_LOCK and a deadlock would occur.  Also the _c_m_d is either
  111.           F_LOCK, F_TLOCK, or F_ULOCK and the number of entries in the lock
  112.           table would exceed the number allocated on the system.
  113.  
  114. NNNNOOOOTTTTEEEESSSS
  115.      Locks are on files, not file descriptors.  That is, file descriptors
  116.      duplicated through _d_u_p(3C) do not result in multiple instances of locks,
  117.      but rather multiple references to the same locks.  Thus if any of the
  118.      descriptors associated with the same file are closed, the locks
  119.      associated with the file are lost.
  120.  
  121. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  122.      chmod(2), close(2), creat(2), fcntl(2), intro(2), open(2), read(2),
  123.      write(2).
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))                                                            LLLLOOOOCCCCKKKKFFFF((((3333CCCC))))
  137.  
  138.  
  139.  
  140. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  141.      Upon successful completion, a value of 0 is returned.  Otherwise, a value
  142.      of -1 is returned and _e_r_r_n_o is set to indicate the error.
  143.  
  144. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS
  145.      Unexpected results may occur in processes that do buffering in the user
  146.      address space.  The process may later read/write data which is/was
  147.      locked.  The standard I/O package is the most common source of unexpected
  148.      buffering.
  149.  
  150.      Because in the future the variable _e_r_r_n_o will be set to EAGAIN rather
  151.      than EACCES when a section of a file is already locked by another
  152.      process, portable application programs should expect and test for either
  153.      value.
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.